home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer)…68k, x86, SPARC, PA-RISC] / NeXTSTEP 3.3 Dev Intel.iso / usr / sybase / doc / dbaltbind.man < prev    next >
Text File  |  1993-04-22  |  13KB  |  287 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                dbaltbind
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbaltbind
  6.  
  7.   FUNCTION:
  8.        Bind a compute column to a program variable.
  9.  
  10.   SYNTAX:
  11.        RETCODE dbaltbind(dbproc, computeid, column, vartype,
  12.                          varlen, varaddr)
  13.  
  14.        DBPROCESS *dbproc;
  15.        int       computeid;
  16.        int       column;
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbaltbind               Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.        int       vartype;
  27.        DBINT     varlen;
  28.        BYTE      *varaddr;
  29.  
  30.   COMMENTS:
  31.  
  32.        o This routine directs DB-Library to  copy  compute  column  data
  33.          returned  by  SQL Server  into  a program variable.  (A compute
  34.          column results from the COMPUTE clause of a Transact-SQL SELECT
  35.          statement.)  When  each new row containing compute data is read
  36.          via dbnextrow() or dbgetrow(), the  data  from  the  designated
  37.          column  in that compute row is copied into the program variable
  38.          with the address varaddr.  There must be a separate dbaltbind()
  39.          call  for  each compute column that is to be copied.  It is not
  40.          necessary to bind every compute column to a program variable.
  41.        o The SQL Server can return two types of rows: regular rows  con-
  42.          taining  data  from  columns designated by a SELECT statement's
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                dbaltbind
  47.   ______________________________________________________________________
  48.          select-list,  and  compute  rows  resulting  from  the  COMPUTE
  49.          clause.    dbaltbind()  binds  data  from  compute  rows.   Use
  50.          dbbind() for binding data from regular rows.
  51.  
  52.        o You must  make  the  calls  to  dbaltbind()  after  a  call  to
  53.          dbresults() and before the first call to dbnextrow().
  54.        o The typical sequence of calls is:
  55.  
  56.          DBCHAR    name[20];
  57.          DBINT     namecount;
  58.  
  59.          /* read the query into the command buffer */
  60.          dbcmd(dbproc, "select name from emp compute count(name)");
  61.  
  62.          /* send the query to SQL Server */
  63.          dbsqlexec(dbproc);
  64.  
  65.  
  66.  
  67.  
  68.   dbaltbind               Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          /* get ready to process the results of the query */
  71.          dbresults(dbproc);
  72.  
  73.          /* bind the regular row data -- name */
  74.          dbbind(dbproc, 1, STRINGBIND, (DBINT) 0, name);
  75.  
  76.          /* bind the compute column data -- count of name */
  77.          dbaltbind(dbproc, 1, 1, INTBIND, (DBINT) 0, (BYTE *) &namecount);
  78.  
  79.          /* now process each row */
  80.          while (dbnextrow(dbproc) != NO_MORE_ROWS)
  81.          {
  82.              C-code to print or process row data
  83.          }
  84.  
  85.  
  86.        o dbaltbind() incurs a little overhead,  because  it  causes  the
  87.          data  to  be  copied  into  a  program variable.  To avoid this
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                dbaltbind
  91.   ______________________________________________________________________
  92.          copying, you can use the dbadata() routine to  directly  access
  93.          the returned data.
  94.  
  95.        o You can only bind a result column to a single program variable.
  96.          If  you  bind  a  result column to multiple variables, only the
  97.          last binding takes effect.
  98.        o Since SQL Server can return null values, DB-Library provides  a
  99.          set  of  default  values,  one  for each datatype, that it will
  100.          automatically substitute when binding null values.  The  dbset-
  101.          null() function allows you to explicitly set your own null sub-
  102.          stitution values.  (See the manual  page  for  the  dbsetnull()
  103.          function for a list of the default substitution values.)
  104.  
  105.   PARAMETERS:
  106.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  107.            connection for a particular front end/SQL Server process.  It
  108.            contains all the information that DB-Library uses  to  manage
  109.  
  110.  
  111.  
  112.   dbaltbind               Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.            communications and data between the front end and SQL Server.
  115.        computeid -  The id that identifies the particular compute row of
  116.            interest.   A  SELECT  statement  may  have  multiple COMPUTE
  117.            clauses, each of which returns a separate compute  row.   The
  118.            computeid  corresponding  to  the  first  COMPUTE clause in a
  119.            SELECT is 1.
  120.        column -  The column number of the row data that is to be  copied
  121.            to  a program variable.  The first column is column number 1.
  122.            Note that the order in which compute columns are returned  is
  123.            determined  by  the order of the corresponding columns in the
  124.            select-list, not by the order in which  the  compute  columns
  125.            were  originally  specified.   For  example, in the following
  126.            query the result of  "sum(price)"  is  referenced  by  giving
  127.            column a value of 1, not 2:
  128.  
  129.                 select price, advance from titles
  130.                      compute sum(advance), sum(price)
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89                dbaltbind
  135.   ______________________________________________________________________
  136.  
  137.            The relative order of compute  columns  in  the  select-list,
  138.            rather  than their absolute position, determines the value of
  139.            column.  For instance, given the following variation  of  the
  140.            previous SELECT:
  141.  
  142.                 select title_id, price, advance from titles
  143.                      compute sum(advance), sum(price)
  144.  
  145.            the column for "sum(price)" still has a value of 1 and not 2,
  146.            because  the  "title_id"  column  in the select-list is not a
  147.            compute column and therefore is ignored when determining  the
  148.            compute column's number.
  149.        vartype -  This describes the datatype of the  binding.  It  must
  150.            correspond  to the datatype of the program variable that will
  151.            receive the copy of the data from the DBPROCESS.   The  table
  152.            below  shows  the correspondence between vartypes and program
  153.  
  154.  
  155.  
  156.   dbaltbind               Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.            variable types.
  159.  
  160.            dbaltbind() supports a wide range of type conversions, so the
  161.            vartype  can  be  different from the type returned by the SQL
  162.            query.  For instance, a SYBMONEY result may  be  bound  to  a
  163.            DBFLT8  program  variable  via  FLT8BIND, and the appropriate
  164.            data conversion will happen automatically.  For a list of the
  165.            data  conversions provided by DB-Library, see the manual page
  166.            for dbwillconvert().
  167.  
  168.            For a list of the typedefs used by DB-Library, see the manual
  169.            page for types.
  170.  
  171.            Here is a list of the legal  vartypes  recognized  by  dbalt-
  172.            bind(),  along with the SQL Server and program variable types
  173.            that each one refers to:
  174.  
  175.  
  176.  
  177.  
  178.   9                       Version 4.0 -- 5/1/89                dbaltbind
  179.   ______________________________________________________________________
  180.               Vartype                 Program variable type     SQL Server type
  181.  
  182.               CHARBIND                DBCHAR                    SYBCHAR
  183.               STRINGBIND              DBCHAR                    SYBCHAR
  184.               NTBSTRINGBIND           DBCHAR                    SYBCHAR
  185.               VARYCHARBIND            DBVARYCHAR                SYBCHAR
  186.               BINARYBIND              DBBINARY                  SYBBINARY
  187.               VARYBINBIND             DBVARYBIN                 SYBBINARY
  188.               TINYBIND                DBTINYINT                 SYBINT1
  189.               SMALLBIND               DBSMALLINT                SYBINT2
  190.               INTBIND                 DBINT                     SYBINT4
  191.               FLT8BIND                DBFLT8                    SYBFLT8
  192.               BITBIND                 DBBIT                     SYBBIT
  193.               DATETIMEBIND            DBDATETIME                SYBDATETIME
  194.               MONEYBIND               DBMONEY                   SYBMONEY
  195.  
  196.            Since SYBTEXT and SYBIMAGE data are never returned through  a
  197.            compute row, those datatypes are not listed above.
  198.  
  199.  
  200.   dbaltbind               Version 4.0 -- 5/1/89                       10
  201.   ______________________________________________________________________
  202.            Note that the SQL Server type in the table  above  is  listed
  203.            merely  for  your  information.  The vartype you specify does
  204.            not necessarily have to correspond to a particular SQL Server
  205.            type, because, as mentioned earlier, dbaltbind() will convert
  206.            SQL Server data into the specified vartype.
  207.  
  208.            The above table shows that four representations for character
  209.            data  are  available.   They  differ according to whether the
  210.            data is blank-padded or null-terminated:
  211.  
  212.               Vartype                 Program type            Padding        Terminator
  213.  
  214.               CHARBIND                DBCHAR                  blanks         none
  215.               STRINGBIND              DBCHAR                  blanks         \0
  216.               NTBSTRINGBIND           DBCHAR                  none           \0
  217.               VARYCHARBIND            DBVARYCHAR              none           none
  218.  
  219.            Note that the "\0" in the table above is the null  terminator
  220.  
  221.  
  222.   11                      Version 4.0 -- 5/1/89                dbaltbind
  223.   ______________________________________________________________________
  224.            character.
  225.  
  226.            If overflow occurs when converting integer or float data to a
  227.            character/text  binding  type,  the  first  character  of the
  228.            resulting value will contain an asterisk  ("*")  to  indicate
  229.            the error.
  230.  
  231.            Binary and image data may be stored in two different ways:
  232.  
  233.               Vartype                 Program type            Padding
  234.  
  235.               BINARYBIND              DBBINARY                nulls
  236.               VARYBINBIND             DBVARBINARY             none
  237.  
  238.            When  a  column  of  integer  data  is  summed  or  averaged,
  239.            SQL Server always returns a 4-byte integer, regardless of the
  240.            size of the column. Therefore,  be  sure  that  the  variable
  241.            which  is  to  contain  the  result  from  such  a compute is
  242.  
  243.  
  244.   dbaltbind               Version 4.0 -- 5/1/89                       12
  245.   ______________________________________________________________________
  246.            declared as DBINT and that the vartype of the binding is INT-
  247.            BIND.
  248.        varlen -  The length of the program variable in bytes.
  249.  
  250.            For fixed-length vartypes, such  as  MONEYBIND  or  FLT8BIND,
  251.            this length is ignored.
  252.  
  253.            For character and binary  types,  varlen  must  describe  the
  254.            total  length  of  the  available  destination  buffer space,
  255.            including any space that may be  required  for  special  ter-
  256.            minating  bytes,  such as a null terminator.  If varlen is 0,
  257.            the total number of bytes available will be copied  into  the
  258.            program  variable.  (For char and binary SQL Server data, the
  259.            total number of bytes  available  is  equal  to  the  defined
  260.            length  of  the database column, including any blank padding.
  261.            For varchar and varbinary data, the  total  number  of  bytes
  262.            available  is  equal  to  the  actual  data  contained in the
  263.  
  264.  
  265.  
  266.   13                      Version 4.0 -- 5/1/89                dbaltbind
  267.   ______________________________________________________________________
  268.            column.) Therefore, if you are sure that your  program  vari-
  269.            able  is large enough to handle the results, you can just set
  270.            varlen to 0.
  271.        varaddr -  The address of the program variable to which the  data
  272.            will be copied.
  273.  
  274.   RETURNS:
  275.        SUCCEED or FAIL.  dbaltbind() returns FAIL if the  column  number
  276.        isn't  valid,  if  the data conversion specified by vartype isn't
  277.        legal, or if varaddr is NULL.
  278.  
  279.   SEE ALSO:
  280.        dbadata, dbbind, dbconvert, dbsetnull, dbwillconvert, types
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.